<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Extending Ibator</title>
  <link type="text/css" rel="stylesheet" href="../ibator.css"/>
</head>
<body>

<div class="menuNav">
  <p>
    <a href="../index.html" target="_top">Show Menu</a>
    <a href="extending.html" target="_top">Hide Menu</a>
  </p>
</div>

<h1>Extending Ibator</h1>
<p>Ibator is designed for extensibility.  All code generation is performed using a
simple DOM representation of Java and XML elements that is included with Ibator.</p>
<p>The Java DOM is included in the package <code>org.apache.ibatis.ibator.api.dom.java</code></p>
<p>The XML DOM is included in the package <code>org.apache.ibatis.ibator.api.dom.xml</code></p>
<p>These classes are not sufficient for every conceivable code generation possibility, but they are quite
useful for generating simple to moderately complex Java and XML code.</p>

<p>Using options in the Ibator configuration file, you can provide your own implementations
of many of Ibator's key interfaces.  You can also subclass any of the provided implementations
to provide customized behaviors.  This page will describe the public APIs available in
Ibator and provide pointers to the source code for further investigation.  If you have
any difficulty understanding how to extend Ibator, feel free to send a note to the
support mailing list at
<a href="mailto:user-java@ibatis.apache.org">user-java@ibatis.apache.org</a>.</p>

<h2>Extending Versus Plugging In</h2>
<p>Although there are a number of different extension points for Ibator, as shown on this
page, in most cases it will be far easier to extend Ibator through the use of a plugin.  See the
<a href="pluggingIn.html">Implementing Ibator Plugins</a> reference page for more information.</p>
<p>The primary extension point for code generation is
<code>org.apache.ibatis.ibator.api.IntrospectedTable</code>.  Implementing a code generator
is a non-trivial task and should only be contemplated when you want to completely replace
the code generation activities of Ibator.  In the years since the original release of Abator,
very few enhancement requests have appeared that could not be handled by a plugin.</p>

<h2>Extension Points</h2>
<p>Ibator includes a number of different extension points.  The following sections
list the different methods of extending Ibator, and describes the types of
activities that can be accomplished with the different extensions.  If you
need some help understanding the different options, feel free to ask a question
on the iBATIS user mailing list.</p>
<h3>org.apache.ibatis.ibator.generator.ibatis2.dao.templates.AbstractDAOTemplate</h3>
<p>Use this extension point if you need to generate DAO objects that are different from
one of Ibator's built-in options.  Classes that extend <code>AbstractDAOTemplate</code>
have the opportunity to override and implement a variety of different methods that
define how the DAO objects should be constructed, and how the DOAs interact with iBATIS.</p>
<p>If you implement this extension point, then you should specify the fully qualified
name of the implementing class on the <code>type</code> attribute of the
<code>&lt;daoGenerator&gt;</code> configuration element.</p>

<h3>org.apache.ibatis.ibator.api.IntrospectedTable</h3>
<p><code>IntrospectedTable</code> is an abstract class that can be extended to supply
different code generators than the versions supplied with Ibator.  A good example of
such an implementation would be a FreeMarker or Velocity template based
implementation of Ibator.  In most other instances, coding a plugin is the better way to go.</p>
<p>If you choose to extend this class, you must supply code to generate Java model classes,
DAO classes, and SQL Map XML files.  You may choose to generated those generators with the
technology of your choice.  You should also ensure that you follow all the Ibator rules for
code generation (for example, do not generate a primary key class if the table doesn't have
a primary key).  The base <code>IntrospectedTable</code> class holds an instance
of <code>org.apache.ibatis.ibator.internal.rules.IbatorRules</code> that can be queried
to determine many of the rules for code generation.</p>
<p>Ibator supplies two implementations of introspected table.  The implementation is chosen
bases on the value of the <code>targetRuntime</code> attribute of the
<code>&lt;ibatorContext&gt;</code> element.  In many cases it will be far simpler
to extend one of the built in implementations, rather than creating an implementation
from scratch.  The following table shows the built in implementations:</p>
<table cellspacing="0" cellpadding="5" border="1">
  <tr>
    <th>TargetRuntime</th>
    <th>Implementation</th>
  </tr>
  <tr>
    <td>Ibatis2Java2 (default)</td>
    <td><code>org.apache.ibatis.ibator.generator.ibatis2.IntrospectedTableIbatis2Java2Impl</code></td>
  </tr>
  <tr>
    <td>Ibatis2Java5</td>
    <td><code>org.apache.ibatis.ibator.generator.ibatis2.IntrospectedTableIbatis2Java5Impl</code></td>
  </tr>
</table>

<p>If you choose to implement this extension point, specify the fully qualified
class name of your implementation with the <code>targetRuntime</code>
attribute of the <code>&lt;ibatorContext&gt;</code> element.</p>

<h3>org.apache.ibatis.ibator.api.IntrospectedColumn</h3>
<p><code>IntrospectedColumn</code> is a class that holds information about a
column as it is returned from database metadata, as well as methods used
during code generation to generate specific phrases for iBATIS.  In some rare
circumstances it might be desirable to override this class to provide
your own implementation - especially if you create a new set of code
generators for Ibator.</p>
<p>If you choose to implement this extension point, specify the fully qualified
class name of your implementation with the <code>introspectedColumnImpl</code>
attribute of the <code>&lt;ibatorContext&gt;</code> element.</p>

<h3>org.apache.ibatis.ibator.api.JavaTypeResolver</h3>
<p>Ibator calls methods in this interface to map JDBC types to Java types
   during database introspection.  The default implementation of this
   interface is <code>org.apache.ibatis.ibator.internal.types.JavaTypeResolverDefaultImpl</code>.
   You can provide your own implementation, and the default implementation has
   been designed for extensibility.</p>

<p>To provide your own implementation, specify the fully qualified class name
   in the XML configuration like this:</p>
<pre>
    &lt;javaTypeResolver type="mypackage.MyImplementation"&gt;
      ...
    &lt;/javaTypeResolver&gt;
</pre>

<h3>org.apache.ibatis.ibator.api.ShellCallback</h3>
<p>Ibator calls methods in this interface to perform functions that it cannot
   do on its own.  The most important of these functions are:</p>
<ul>
  <li>Translating project/package into a directory structure</li>
   <li>Merging Java source files in the event that an existing Java file of
     the same name/package exists.</li>
</ul>

<p>The default implementation of this interface is
   <code>org.apache.ibatis.ibator.internal.DefaultShellCallback</code>.  The default
   implementation simply concatenates project and package together and creates
   the necessary package directories if needed.  The default implementation does not
   support merging of Java files, and will either overwrite or ignore files.</p>

<p>You can provide your own implementation.  This would be the most important
   class to write if you want to integrate Ibator into some other environment.
   For example, the Eclipse plugin provides an implementation of this interface that
   supports Java file merging when running in the Eclipse environment.</p>

<p>To provide your own implementation, supply an instance of the interface
   on the constructor to the <code>org.apache.ibatis.ibator.api.Ibator</code>
   object.  This cannot be configured through XML.  If you are providing
   your own implementation of this interface then we assume that you are
   also providing some collateral code (like a new Ant task) to run
   your implementation.</p>

<h3>org.apache.ibatis.ibator.api.ProgressCallback</h3>
<p>Ibator calls methods in this interface to report progress during the
   generation of files (a long running process).  The default implementation
   of this interface is
   <code>org.apache.ibatis.ibator.internal.NullProgressCallback</code>
   which simply ignores all progress messages.  You can provide an
   implementation of this interface to support progress notifications and
   cancellation of file generation.</p>

<p>Implementing this interface would be important when integrating Ibator
   into other IDE environments.  The Eclipse plugin provides an implementation
   of this interface that hooks into Eclipse's progress notification system.</p>

<p>To provide your own implementation, supply an instance of the interface
   in the <code>org.apache.ibatis.ibator.api.Ibator.generate()</code> method call.
   This cannot be configured through XML.  Again, we assume that if you are providing
   your own implementation of this interface then you are
   also providing some collateral code (like a new Ant task or an IDE integration) to run
   your implementation.</p>
</body>
</html>
